home *** CD-ROM | disk | FTP | other *** search
/ Mac Expert 1995 Winter / Mac Expert - Winter 95.iso / Les fichiers / Utilitaires divers / Images / Mac POV Utils 1.1 ƒ / POV-Utils Docs.Raw / Swoop / SWOOP.DOC < prev    next >
Encoding:
Text File  |  1992-09-13  |  12.4 KB  |  313 lines  |  [TEXT/ttxt]
  1.                                Swoop v0.1 beta
  2.                               by Douglas Otwell
  3.  
  4.                           User Guide and Reference
  5.  
  6.  
  7. WARNING:  Swoop v0.1b is a BETA version of the program.  Therefore it
  8.           can be expected to have bugs and rough spots.  By using this
  9.           program, you will have become a beta tester.
  10.  
  11.  
  12.  
  13. TABLE OF CONTENTS
  14. =================
  15.   1.  Overview
  16.   2.  Disclaimer
  17.   3.  Run Instructions
  18.   4.  Application Notes
  19.   5.  Acknowledgements
  20.   6.  Contacting the Author
  21.  
  22.         
  23.  
  24. 1.  OVERVIEW
  25. ============
  26.  
  27. Requirements:  Swoop requires POV-Ray to render the resulting object.
  28.                Swoop requires the utility Raw2POV, by Steve Anger, to 
  29.                convert Swoop output into POV-Ray input.
  30.                Polyray, by Alexander Enzmann, is not required, but
  31.                is very useful as a previewer.
  32.  
  33. Swoop is a little utility I've been developing to create objects for the
  34. POV-Ray raytracer. POV-Ray is a raytracer originally written by David Buck, 
  35. and substantially enhanced by the POV team, lead by Drew Wells.
  36.  
  37. Swoop creates swoop surfaces, using a collection of POV-Ray triangle
  38. primitives.  A swoop surface is like a sweep surface, with a twist.  Swoop
  39. surfaces are created by sweeping a two-dimensional polygon through space, 
  40. in a pre-defined path, and connecting the sides of the polygon with 
  41. triangles, resulting in a tube-like object with a cross-section of the
  42. original polygon.  Extrusions can be done by translating the polygon in a
  43. straight line.  Surfaces of rotation are done by sweeping the polygon in
  44. a circle.  More complex shapes can be made by combining translations, 
  45. rotations, and scaling of the polygon while it is being swept (or swoopt.)
  46.  
  47. Swoop generates raw triangle data only.  Swoop relies on a gem of a program
  48. written by Steve Anger called Raw2POV.  This program takes raw triangle
  49. data, generated by Swoop or other means, and smooths and bounds and formats 
  50. the data for use by POV-Ray. 
  51.  
  52. Swoop is executed from the command line, and reads an ascii text file for its
  53. parameters.  No preview mode is available.  Swoop has basic abilities to
  54. output Polyray data.  Polyray is another raytracer, written by
  55. Alexander Enzmann.  For these purposes, its distinguishing characteristic is
  56. a "scan conversion" mode, which is very very quick at rendering the Swoop
  57. output, and therefore I use it as a previewer.  (Polyray is a sophisticated
  58. and powerful raytracer in its own right.)
  59.  
  60.  
  61.  
  62. DISCLAIMER                     
  63. ==========
  64. This program is offered as is, with no warranties, expressed or implied,
  65. regarding its correctness or suitability.  I will not be responsible for any
  66. damage this program may cause to your data, software, hardware or social life.
  67.  
  68.  
  69. 3.  RUN INSTRUCTIONS
  70. ====================
  71.  
  72. 3.1  Creating the Swoop Input File
  73. ----------------------------------
  74. The swoop input file is an ascii text file created with your favorite text
  75. editor.  Let's start with an example to see how this works.
  76. In this example, we're beginning with a 2-unit square in the y-z plane, and
  77. we're going to extrude it by sweeping it from left to right.  Just for kicks,
  78. we want to twist it a half turn as we sweep.
  79. The input file will look like the following. (This is from the included 
  80. file EXAMPLE1.TXT.  The results can be seen in the top left corner of
  81. EXAMPLES.GIF.)
  82.  
  83.  
  84. outfile test.inc
  85. name example1
  86. output_type 1
  87. segments 30
  88.  
  89. vertex 0 1 1
  90. vertex 0 1 -1
  91. vertex 0 -1 -1
  92. vertex 0 -1 1
  93.  
  94. var 1 0 180
  95. var 1 -5 5
  96.  
  97. rotate &1 0 0
  98. translate &2 0 0
  99.  
  100.  
  101. The first section of this example contains keywords describing the 
  102. object we're creating: the output file name, name of the object, the type
  103. of output (raw or Polyray syntax), and the total number of segments to create.
  104.  
  105. The next section lists the vertices of the polygon.  Up to 24 vertices are
  106. allowed; Swoop will always connect the last to the first to close the
  107. polygon.
  108.  
  109. The third section defines the variables that will be used.  Currently only
  110. straight-line variables are allowed.  You specify a start and stop value,
  111. and Swoop will interpolate those values for each segment of the surface.
  112.  
  113. The final section describes the path that will be swept out by the polygon.
  114. It consists of up to 24 transformations (translate, rotate, or scale)
  115. that will be done on the polygon for each segment.  The arguments may be
  116. constants, or may be the result of interpolating one of the variables 
  117. described in the previous section.  For variable arguments, a &n is used,
  118. where n references the var definition; 1=first, 2=second, etc.
  119.  
  120. In the example above, we are going to rotate the square around the x-axis
  121. using variable definition #1 (from 0 to 180).
  122. At the same time, we'll translate the square from -5 to 5 on the x-axis, 
  123. using the second variable definition.
  124.  
  125. The swoop object is formed by connecting each side of the polygon with the
  126. same side of the new, transformed polygon, using two triangles.  The 
  127. smoothness of the resulting polyhedron can be adjusted by using more or fewer
  128. sides, and more or fewer segments.
  129.  
  130. For more information on each keyword, see the Swoop Keywords section, below.
  131.  
  132. 3.2  Running Swoop
  133. ------------------
  134.  
  135. Once your input file is created, produce the output file by calling Swoop
  136. from the command-line, and specifying the full name of the input file, e.g.:
  137.  
  138. Swoop example1.txt
  139.  
  140. A file will be created with the name and format specified in the input file.
  141.  
  142. WARNING: any existing file with the name specified by the outfile keyword 
  143. will be overwritten without warning.
  144.  
  145. Three command-line switches are provided to override settings in the input
  146. file:
  147.  
  148. -ofilename will override the output file name to filename
  149. -p will force Polyray output
  150. -r will force raw triangle output
  151.  
  152. 3.3  Previewing with Polyray
  153. ----------------------------
  154.  
  155. If you specified Polyray output (output_type 1), you'll next want to run 
  156. Polyray.  A sample Polyray input file, TEST.PI, is included in this
  157. distribution.  You'll need to change the #include line to specify the 
  158. file you created with Swoop, and replace the word "test" inside the object
  159. description with the name you specified for your object.  You will probably 
  160. also have to adjust the camera position and look_at. Then:
  161.  
  162. Polyray test.pi -V1 -W -S
  163.  
  164. will display the object on screen in VGA mode, and write a sixteen-bit 
  165. targa file called OUT.TGA.
  166.  
  167. For details on running Polyray, consult the Polyray documentation.
  168.  
  169. 3.4  Running Raw Data Through Raw2POV
  170. -------------------------------------
  171.  
  172. If you created raw triangle data with Swoop, you'll need to run it through
  173. Raw2POV before POV-Ray can make use of it.  Raw2POV does all the hard work
  174. of calculating normals, and bounding and formatting the triangles to produce
  175. smooth triangle primitives for POV-Ray.  The results look spectacular and
  176. trace quite quickly. The command line will look like:
  177.  
  178. raw2pov example1.raw -s180
  179.  
  180. The -s180 will smooth all triangles.  Omit this if you don't want smoothing
  181. done.
  182.  
  183. Raw2POV creates two files; EXAMPLE1.INC, containing the POV-Ray triangle data,
  184. and EXAMPLE1.POV, which has the texture definitions, the composite 
  185. definition with the #include example1.inc, and an overall bounding box.  This
  186. is the file you will want to insert into your POV-Ray scene file. 
  187.  
  188. Swoop creates a separate object for each face of the swoop surface.  Raw2POV
  189. will combine these into a single composite definition and create a texture
  190. for each surface.  See the Application Notes for more details.
  191.  
  192. For details on running Raw2POV, consult the Raw2POV documentation.
  193.  
  194. 3.5  Running POV-Ray
  195. --------------------
  196.  
  197. After splicing in example1.pov into your POV-Ray data file, run POV-Ray as
  198. you normally would.  Be forewarned; smooth triangles parse slowly, and can
  199. require large amounts of RAM.
  200.  
  201. 3.6 Swoop Keywords
  202. --------
  203.  
  204. This section contains details for each keyword that Swoop understands.
  205.  
  206.  
  207. outfile      This specifies the name of the file that Swoop will write its
  208. -------      triangle data to.  A complete path may be specified.  This
  209.              file will be overwritten if it already exists.
  210.  
  211. name         Use this to assign a name to the objects you create.  In raw 
  212. ----         mode, Swoop will create a separate object for each face of 
  213.              the swoop. They will be named name_side1, name_side2, etc.  
  214.              If name is not specified, it will default to "swoop."
  215.  
  216. output_type  This indicates the format of the output: 1 = Polyray, 2 = raw.
  217. -----------
  218.  
  219. segments     Specifies the number of segments Swoop will generate.  The
  220. --------     total number of triangles generated is #segments * #sides * 2.
  221.  
  222. vertex       This keyword specifies a polygon vertex.  The order in which
  223. ------       vertices are specified is important.  To create triangles with
  224.              their normals pointing outward (which is what you want,) the
  225.              polygon vertices must be specified in the proper order.  To
  226.              determine this, take your _right_ hand and point your thumb
  227.              in the direction that the polygon will be swept in.  Then your
  228.              fingers will curl in the direction in which the vertices must be
  229.              specified.  If your swoop surface turns out very dark, you
  230.              probably have the vertices in the wrong order.
  231.  
  232. var          This is the variable definition. The first argument specifies
  233. ---          the variable type.  Currently only type 1, linear variables, are
  234.              implemented.  The next two arguments are the start and stop 
  235.              values. The value of the variable will range from the first value
  236.              to the second.
  237.  
  238. rotate       The rotate keyword specifies that the polygon is to be rotated 
  239. ------       between each segment.  Three arguments specify rotation around
  240.              the x, y, and z axes, just as with POV-Ray.  Use it to create
  241.              surfaces of revolution, or combine it with other transforms for
  242.              other effects.  Rotation is done around the "world" origin.
  243.  
  244. translate    Translate is used, obviously, to translate the polygon.  It can
  245. ---------    be used to create extrusions or more complex shapes.
  246.  
  247. scale        The polygon may be scaled as it is being swept.  As with POV-Ray
  248. -----        scaling is done around the "world" origin.
  249.  
  250.  
  251. 4.  Application Notes
  252. =====================
  253.  
  254. Included in this distribution are four example swoop input files:
  255. EXAMPLE1.TXT through EXAMPLE4.TXT.  The results of these, created by
  256. Polyray, are included as EXAMPLES.GIF.
  257.  
  258. All the example files use simple, regular polygons.  Don't be limited. Use
  259. graph paper to layout your own complex polygons.
  260.  
  261. The temptation is to use more segments than needed to get a smooth look. 
  262. Start small, and add segments if needed.
  263.  
  264. Swoop creates each face of the swoop surface as a separate object.  This
  265. allows you to color each face separately.  More importantly, it gives you
  266. control over how your swoops are smoothed.  Normally faces are not smoothed
  267. together, resulting in sharp edges that follow the corners of the polygon.
  268. If you want to smooth these edges, use a text editor to delete the lines
  269. in yourfile.raw that specify a new object name, eg: "name_side1".  You can
  270. selectively smooth sides together by deleting specific side names.
  271.  
  272. Swoop makes no attempt to prevent degenerate triangles (triangles with 
  273. duplicated or co-linear vertices.)  Polyray and Raw2POV both seem to 
  274. handle these gracefully.
  275.  
  276. The source code for Swoop is included in the distribution.  For a time, I 
  277. will be coordinating changes and new releases of Swoop.  I ask that any ideas 
  278. or code enhancements you have, you send to me for inclusion in the next 
  279. release.  See the following section on Contacting the Author.
  280.  
  281.  
  282. 5.  Acknowledgements
  283. ====================
  284.  
  285. First and foremost I want to thank David Buck, original author of the DKBTrace 
  286. raytracer that is the basis of POV-Ray.  Then Drew Wells and the POV team, 
  287. who have made substantial enhancements to that program.
  288.  
  289. Thanks also to Steve Anger for Raw2POV, which makes possible any number of
  290. nifty triangle generators for POV-Ray, written by hacks like myself.
  291.  
  292. And thanks to Alexander Enzmann for Polyray and its scan conversion feature.
  293.  
  294. Raw2POV and Polyray can be found in the COMART forum on CompuServe, or on
  295. the You Can Call Me Ray bulletin board.
  296.  
  297. 6.  Contacting the Author
  298. =========================
  299.  
  300. I am very interested in hearing your comments and suggestions regarding 
  301. Swoop or raytrace graphics in general.  I'm also interested in seeing how you 
  302. make use of Swoop.  You can usually find me lurking on the following 
  303. BBSs:
  304.  
  305. Compuserve               GO COMART     76236,1121
  306. You Can Call Me Ray BBS  708-358-5611  Douglas Otwell
  307.  
  308. or write me at:
  309.  
  310. Douglas Otwell
  311. 2750 Hurd Ave
  312. Evanston, IL 60201
  313.